Using the Visual Studio Tools for the Office System Power Tools Version 1.0.0.0

Summary: Learn about the Microsoft Visual Studio Tools for the Office System Power Tools, a set of developer tools designed to complement Visual Studio Tools for Office. (13 printed pages)

Andrew Whitechapel, Microsoft Corporation

June 2008

Applies to: Microsoft Visual Studio Tools for the Office system 3.0, 2007 Microsoft Office System, Microsoft Office SharePoint Server, Microsoft Visual Studio 2005

Contents

• Overview of the Power Tools

• What Is Included in the Power Tools v1.0 Toolset?

• Open XML Package Editor

• Ribbon IDs Tool Window

• Office Custom UI Manager

• Office Interop API Extensions

• SharePoint Feature Sweeper

• SharePoint Workflow Package Generator

• VSTO/VSTA Pipeline Verfier

• VSTO Developer Cleaner

• VSTO Troubleshooter

• Conclusion

• Additional Resources

Overview of the Power Tools

Microsoft Visual Studio Tools for the Office System (Visual Studio Tools for Office) and Visual Studio Tools for Applications are included with some Microsoft Office system releases and Microsoft Visual Studio releases. To meet the demands of frequent releases, we trim our feature set aggressively. Inevitably, this means that there are some features that we would like to release but that we are prevented from releasing by time constraints. The Microsoft Visual Studio Tools for the Office System Power Tools (Visual Studio Tools for Office Power Tools) are a set of tools that we release alongside Visual Studio, to provide additional functionality. To release these tools in a timely manner, they undergo only simple testing, and are therefore unsupported. You can download the Visual Studio Tools for the Office System Power Tools version 1.0.0.0 from the Microsoft Download Center.

Installing the Tools

The download consists of a .zip file that includes three separate installer packages:

• VSTO_PTRibbonIDs.exe installs the Ribbon IDs Tool Window.

• VSTO_PTExtLibs.exe installs the Office Interop API Extensions and Custom UI Manager.

• VSTO_PT.exe installs all other power tools.

All packages install their files under %PROGRAM FILES%\Microsoft\Microsoft VSTO Power Tools 1.0.

What Is Included in the Power Tools v1.0 Toolset?

There are nine tools in the first release of the Visual Studio Tools for Office Power Tools, including two run-time tools and seven design-time tools, as described in Table 1.

Table 1. Summary of the Visual Studio Tools for Office Power Tools

Tool	Description	Type of Tool
Open XML Package Editor	A graphical treeview-based editor for examining and editing Open XML Package files (including Microsoft Office Word, Microsoft Office Excel, and Microsoft Office PowerPoint documents).	Add-in to Visual Studio.
Ribbon IDs Tool Window	A custom tool window that displays all re-usable built-in Office Ribbon IDs.	Add-in to Visual Studio.
Office Custom UI Manager	A set of classes for coordinating multiple instances of Ribbon, custom task pane, and custom form region objects.	Runtime class library and sample source code.
Office Interop API Extensions	A set of Microsoft Visual C# classes for handling parameterized properties and optional/named parameters, and for LINQ-enabling Office collection objects.	Runtime class library.
SharePoint Feature Sweeper	A GUI tool that cleans up unwanted SharePoint features from the developer's environment.	Stand-alone Microsoft Windows Forms application.
SharePoint Workflow Package Generator	A tool to package a SharePoint workflow project so that it can be deployed.	Scriptable command-line tool.
VSTO/VSTA Pipeline Verifier	A GUI tool that reflects over custom pipeline assemblies to validate the complete Visual Studio Tools for Applications pipeline.	Stand-alone Windows Forms application.
VSTO Developer Cleaner	A GUI tool that removes leftover build artifacts from the developer's computer.	Stand-alone Windows Forms application.
VSTO Troubleshooter	A diagnostic tool that examines a computer looking for the necessary prerequisites for running Visual Studio Tools for Office solutions.	Stand-alone Windows Forms application.

Each of these tools is described in more detail in the following sections.

Open XML Package Editor

The Open XML Package Editor is a Microsoft Visual Studio 2008 add-in that enables parsing and editing of Open Packaging Conventions files, including Word, Excel. and PowerPoint documents. Features include:

• Open any Microsoft Office 2007 Open XML Package file or XPS Package file directly in Visual Studio.

• Browse the tree view of the package file intuitively.

• Open any XML part directly in the rich Visual Studio XML editor.

• Easily use the user interface to add and remove parts and relationships.

• Import and export part contents to and from files.

• Detect when a package file that is open in Visual Studio is modified externally. It prompts you to reload without having to close any open XML part editors.

• Create new Office packages from a set of templates by clicking New Dialog on the Visual Studio File menu.

Figure 1 shows the treeview that is provided when you open an Open XML Package file in Visual Studio.

Figure 1. Open XML Package treeview in Visual Studio

From the treeview, if you double-click any XML part in the file, that part is opened in the standard Visual Studio XML editor, as shown in Figure 2.

Figure 2. XML part open in the Visual Studio XML editor

Ribbon IDs Tool Window

The Ribbon IDs Tool Window provides a Visual Studio custom tool window that displays all the reusable Office images and their IDs. The add-in puts an "ImageMso Window" item on the Tools menu. Click this item to open the custom tool window. You can float or dock the tool window.

In the tool window, when you hover over a button, the tooltip shows you the imageMso ID. When you click a button, the imageMso ID is copied to the Clipboard. If you are also using the VSTO Ribbon designer, you can then paste from the clipboard into the OfficeImageId property field, to give your control the specified standard Office icon image. You can also drag to copy the imageMso ID from a button to a text-based source file in Visual Studio (such as your Ribbon XML if you are not using the Visual Studio Tools for Office ribbon designer).

Figure 3 shows Visual Studio open with a Visual Studio Tools for Office Excel 2007 add-in project, and the Visual Studio Tools for Office Ribbon designer. The custom tool window is docked to the right.

Figure 3. Ribbon IDs custom tool window

Some Office images have multiple image sizes (typically 32x32 and 16x16). Other Office images are provided in only a single size ( 32x32, 24x24, or 16x16). This tool renders all images in either 32x32 or 16x16 format, regardless of the original size of the native image. You can choose whether your Ribbon customization uses large (32x32) or small (16x16) images, and see how each image will render (regardless of its original native size).

A simple search capability is also provided. You can type in any string, and the tool returns a set of images where the string is found within the image ID string. For example, Figure 4 shows the results of searching for the string "data", and displaying 16x16 images.

Figure 4. Ribbon IDs tool window search results

Office Custom UI Manager

In multiple document interface (MDI) applications like Excel and PowerPoint, there is one main frame window, which is used by all workbooks or presentations. Custom task panes are associated with this main frame window. Therefore, by default, any custom task pane is always available to any workbook.

This is not the case with Word, Microsoft Office InfoPath and Microsoft Office Outlook. In Word and InfoPath there are multiple instances of this frame window, one for each document or form that you open. So, when you create a custom task pane in Word or InfoPath, it is attached to whichever is the active document frame, and it is not visible in any other document frame.

The situation is slightly different in Outlook because the user can have multiple Inspector windows open, each of which supports custom task panes. Outlook Explorer windows also support custom task panes. In addition, Outlook supports custom form regions. By default, there is no indication within a custom task pane or form region as to which specific window it is associated with.

This tool is a reusable set of classes that provides a mechanism to synchronize a window (whether it is a Word document window, an InfoPath form window, or an Outlook Inspector or Explorer window) and the custom task panes that are associated with that window. For Outlook, it also enables you to synchronize a window and the custom form region that is associated with it.

The tool provides a special UIContainer class instance associated with each window. You can use this instance as an entry point for all components associated with the window. The tool also provides another class, called UIManager. You can use this class to manage the list of available containers. UIManager also provides mapping between window instances and UIContainer classes.

Office Interop API Extensions

The Office Interop API Extensions tool uses new features found in Microsoft .NET Framework 3.5 and Microsoft Visual C# 3.0 to wrap the Office object model and provide a more productive environment for the C# developer. Specifically, it employs extension methods, object initializers, and nullable types to create a simplified, strongly-typed, and, in some cases, Microsoft Visual Basic–like API. It is not a complete managed API for Office, but is designed to augment the raw object model in useful ways.

The Office object model was originally targeted at dynamic languages such as Microsoft Visual Basic for Applications (VBA) and Visual Basic. As such, it makes extensive use of some of their capabilities, such as late-binding and optional parameters. Being an early-bound and strongly-typed language, C# can be awkward, tedious, and error prone when used in this context. The Office Interop API Extensions, with its simplified and strongly-typed API, enables C# developers to be as productive in this context as Visual Basic developers.

For example, the library includes support for optional parameters, and for parameters that are typically passed by reference. Figure 5 shows examples of code, both with and without using this library.

Figure 5. Optional parameters and reference parameters

The library includes similar time-saving support for named parameters, and for parameterized properties. In addition, the library includes extensive support for using LINQ-friendly syntax in your code when iterating over the various collections in the Office application object models. Figure 6 shows how you can use the LINQ to DASL implementation in the library to query Outlook data without constructing raw SQL-like query strings.

Figure 6. Office collections made LINQ-friendly

SharePoint Feature Sweeper

Each time a Visual Studio Tools for Office SharePoint Workflow solution is debugged in Visual Studio 2008, the SharePoint feature is installed in the SharePoint file system and data is added to the SharePoint database. If the same document library is used for debugging many feature projects, these artifacts begin to clutter the environment.

Further, if all the workflow features are configured to start automatically when a new item is saved or when an item is changed, they will all attempt to start. If there are very many workflow features, this may significantly affect your experience—especially if features that are not currently being debugged fail or if they have resource-intensive operations. You can remove or disable the associated workflows manually by using the Microsoft Office SharePoint Server 2007 user interface, but that can be time-consuming.

The SharePoint Feature Sweeper tool is designed to alleviate this problem. When the tool starts, it searches the local server running Office SharePoint Server for all installed workflow features. These are then listed in a list control, identified by workflow and feature. Each entry is accompanied by a check box control, which is checked by default. You can use these check boxes to indicate which installed workflow features you want to remove from Office SharePoint Server. When you click Remove, the workflow features selected in the list are removed. The Remove button is enabled only if there are items in the list that are selected.

Figure 7. SharePoint Feature Sweeper

SharePoint Workflow Package Generator

Visual Studio Tools for Office improves the developer experience for creating, debugging, and modifying workflow projects for Microsoft Office SharePoint Server 2007. A SharePoint workflow customization is one type of a SharePoint feature. After you create, debug, and test a SharePoint workflow feature, you need to hand it over to the Office SharePoint Server system administrators, along with all of the artifacts they need to install the completed solution on a staging or production server. Typically, this is done by using a Windows SharePoint Solution Package (WSP).

A WSP is essentially a cabinet (CAB) file with a very specific set of contents. The administrator can run the SharePoint administration command-line tool (stsadm.exe) on the WSP to install and activate the solution on the server.

The SharePoint Workflow Package Generator builds a WSP file that contains relevant artifacts and metadata from the current Visual Studio Tools for Office SharePoint workflow project. You can use the tool from a command prompt (including as a post-build step), or you can add a script to the Visual Studio build tasks to cause the tool to run automatically after Visual Studio builds a project. The following is an example command prompt entry:

"c:\Program Files\Microsoft VSTO Power Tools 1.0\workflowpackagegen.exe" /featureManifest:feature.xml

Table 2. Command-line switches

Command-Line Switch	Required or Optional	Purpose
/featureManifest:value	Required	Specifies the location of the feature manifest file.
/outputPath:value	Optional	Specifies the output path for the WSP file (the default location is the same directory as the feature manifest).
/?, /help	Optional	Shows command usage message.

The following is an example of incorporating the tool into the project as an MSBuild task:

<Target Name="AfterBuild">
    <Exec Command="&quot;c:\Program Files\Microsoft VSTO Power Tools 1.0\workflowpackagegen.exe&quot; /featureManifest:feature.xml" ContinueOnError="true">
    </Exec>
</Target>

You specify a feature manifest file as an input, and the tool generates a manifest.xml file, a DDF file, and the WSP file as output. You have the option to specify the location where the outputs are generated.

VSTO/VSTA Pipeline Verifier

The Pipeline Verifier is used to verify the integrity of a given Visual Studio Tools for Office/Visual Studio Tools for Applications pipeline. In Visual Studio 2008, the Visual Studio Tools for Office runtime is layered on top of the Visual Studio Tools for Applications runtime, and it uses the default Visual Studio Tools for Applications pipeline. You can use the tool in GUI mode or in command-prompt mode.

To run the tool in GUI mode, double-click PipelineVerifier.exe. If the Visual Studio Tools for Office/Visual Studio Tools for Applications runtime is installed (which lays down the default Visual Studio Tools for Office/Visual Studio Tools for Applications pipeline) the default pipeline path displays, as shown in Figure 8.

Figure 8. VSTA Pipeline Verifier showing the default pipeline

You can either accept the default pipeline or specify a custom pipeline. Then, click Display Pipeline to display the details about the specified pipeline.

The tool also displays information about non-participating types in the pipeline assemblies. These types may be used in add-in load scenarios but they do not directly contribute to creating the pipeline. The combo boxes at the bottom of the tool window display lists of non-participating host adapters, add-in adapters, contracts, and views.

To test load an add-in with the displayed pipeline, specify the add-in path and the add-in class, and then click Test discovery for the add-in. If the load succeeds, a success message displays; otherwise an error is shown with the appropriate stack trace. To load the add-in, all possible views discovered in the pipeline are attempted.

Figure 9 shows an example of a test Excel add-in assembly built as ExcelAddIn1.dll, with an add-in class named ExcelAddIn1.ThisAddIn.

Figure 9. Testing the discoverability of an Excel add-in

To run the tool in command-prompt mode, execute PipelineVerifier.exe at the command prompt by using the /silent switch. This disables the GUI display and logs the pipeline information as an XML file in the current working directory. Command-prompt mode is more useful for build tasks and scripting. For more information about the functionality of this tool, please see the help document installed with the tool.

VSTO Developer Cleaner

Visual Studio 2008 includes options to "Clean" a project or solution—that is, to remove the build artifacts left by a project. But this does not remove all build artifacts. The standard clean option removes most of the output files from the target folder, and some registry entries, but not all registry entries. You typically create multiple Visual Studio projects on a computer, including test projects, prototypes, and production projects, which can result in many unwanted build artifacts over time. Many of these artifacts are not particularly discoverable, and it is not always obvious which items can be safely deleted. This tool provides a simple way to identify and remove these artifacts.

The tool enables you to list and remove either single instances or multiple instances of the following artifacts:

• Add-in registry entries

• Temporary certificates in the current user's personal store

• The current user's inclusion list entries created for debugging purposes

The tool offers three tabs, to correspond with these three categories of artifact, as shown in Figures 10–13. In each case, you can remove selected entries or all entries.

Finding Add-in Registry Entries

When a Visual Studio Tools for Office add-in is built, Visual Studio registers it for debugging purposes. This registration includes the standard Manifest key. This key includes an additional "|vstolocal" tag that prevents the Visual Studio Tools for Office runtime from installing it into the ClickOnce cache. Deleting these entries will cause the add-in to not load. Calling build in the project may not recreate these entries unless a recompile occurs (you must either clean and rebuild the project or change the project in a way that causes it to rebuild). The tool finds all Manifest keys in the registry that have the "|vstolocal" tag.

Figure 10. Office add-in registry entries

Comparing Temporary Certificates in the Personal Store

When a Visual Studio Tools for Office solution is built, a certificate must be used to sign the solution. If a valid certificate is not provided, a temporary "self cert" certification is created, added to the project, and then copied into the current user's personal store. The tool compares the issuer and the subject of the certificates in the store, and reports self certs in the list. If you accidently delete a self cert to a project you are still working with, the next time the solution is built the self cert will be added back into the personal store. Removing these certificates has no effect on the run-time behavior of Visual Studio Tools for Office customizations.

Figure 11. Temporary certificates in the user's personal store

Creating Inclusion List Entries

When a Visual Studio Tools for Office solution is published and installed, if the solution's certificate is not explicitly trusted, a trust prompt that asks the user if they want to install the solution occurs. When the user responds to this prompt, the trust decision is persisted in the Visual Studio Tools for Office inclusion list. The Visual Studio Tools for Office inclusion list is a special set of registry keys. Visual Studio 2008 also automatically creates inclusion list entries for locally-built Visual Studio Tools for Office customizations on your development computer. Deleting these entries means the solution will not be trusted, and a trust prompt will occur if the solution is still registered when the customized application or document is next opened.

Figure 12. User inclusion list entries created for debugging purposes

VSTO Troubleshooter

The VSTO Troubleshooter tool is a stand-alone application designed to help diagnose potential client-side issues when you deploy a Visual Studio Tools for Office solution. The tool scans the client computer for the prerequisites required to run a Visual Studio Tools for Office solution and reports the state of the prerequisites in an HTML report. The tool also provides links to information about how to resolve the issue when a prerequisite is not found on the client computer. This is an update to a tool that was previously available for Visual Studio 2005 Tools for Office SE solutions, described here in the article Troubleshooting Deployment Errors in Visual Studio 2005 Tools for the Office System SE.

The tool checks for the correct installation of the supported Office products, the Office primary interop assemblies (PIAs), the Visual Studio Tools for Office runtime, the .NET Framework, and several registry and configuration settings, as shown in Figure 13.

Figure 13. VSTO Troubleshooter

Conclusion

The Visual Studio Tools for Office team is dedicated to providing a rich, professional toolset and run-time framework. We also recognize the need for additional support tools, and are committed to releasing these tools alongside the main product. Although the tools are not supported, we welcome any feedback, and we intend to post updates to the download periodically. These updates will likely include software updates and added features, and additional new tools.

Additional Resources

For more information, see the following resources.

• Microsoft Visual Studio Tools for the Office System Power Tools v1.0.0.0

• Visual Studio 2005 Tools for Applications Software Development Kit (SDK)

• Visual Studio Tools for the Office System (3.0)